<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Progress/SplashImage</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<style type="text/css">
.square {
  width: 22px;
  height: 22px;
  border: 1px solid #000000;
}
</style>
</head>
<body>

<h1>Progress / SplashImage</h1>

<p>Creates or updates a window containing a progress bar or an image.</p>

<pre class="Syntax">SplashImage, Off
SplashImage [, ImageFile, Options, SubText, MainText, WinTitle, FontName]

Progress, Off
Progress, ProgressParam1 [, SubText, MainText, WinTitle, FontName]</pre>
<h3>Parameters</h3>
<dl>

  <dt>ImageFile</dt>
  <dd><p>If this is the word OFF, the window is destroyed. If this is the word SHOW, the window is shown if it is currently hidden.</p>
      <p>Otherwise, this is the file name of the BMP, GIF, or JPG image to display (to display other file formats such as PNG, TIF, and ICO, consider using the <a href="Gui.htm">Gui</a> command to create a window containing a picture control).</p>
      <p><span class="ver">[AHK_L 59+]:</span> Any image format supported by Gui may be used with SplashImage.</p>
      <p><em>ImageFile</em> is assumed to be in <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> if an absolute path isn't specified. If <em>ImageFile</em> and <em>Options</em> are blank and the window already exists, its image will be unchanged but its text will be updated to reflect any new strings provided in <em>SubText</em>, <em>MainText</em>, and <em>WinTitle</em>.</p>
      <p>For newly created windows, if <em>ImageFile</em> is blank or there is a problem loading the image, the window will be displayed without the picture.</p></dd>

  <dt>ProgressParam1</dt>
  <dd><p><u>If the progress window already exists</u>: If <em>Param1</em> is the word OFF, the window is destroyed. If <em>Param1</em> is the word SHOW, the window is shown if it is currently hidden.</p>
      <p>Otherwise, if <em>Param1</em> is an pure number, its bar's position is changed to that value. If <em>Param1</em> is blank, its bar position will be unchanged but its text will be updated to reflect any new strings provided in <em>SubText</em>, <em>MainText</em>, and <em>WinTitle</em>. In both of these modes, if the window doesn't yet exist, it will be created with the defaults for all options.</p>
      <p><u>If the progress window does not exist</u>: A new progress window is created (replacing any old one), and <em>Param1</em> is a string of zero or more options from the list below.</p></dd>

  <dt>Options</dt>
  <dd><p>A string of zero or more  options from the list further below.</p></dd>

  <dt>SubText</dt>
  <dd><p>The text to display below the image or bar indicator. Although word-wrapping will occur, to begin a new line explicitly, use linefeed (`n). To set an existing window's text to be blank, specify <a href="../Variables.htm#Space">%A_Space%</a>. For the purpose of auto-calculating the window's height, blank lines can be reserved in a way similar to <em>MainText</em> below.</p></dd>

  <dt>MainText</dt>
  <dd><p>The text to display above the image or bar indicator (its font is semi-bold). Although word-wrapping will occur, to begin a new line explicitly, use linefeed (`n).</p>
      <p>If blank or omitted, no space will be reserved in the window for <em>MainText</em>. To reserve space for single line to be added later, or to set an existing window's text to be blank, specify <a href="../Variables.htm#Space">%A_Space%</a>. To reserve extra lines beyond the first, append one or more linefeeds (`n).</p>
      <p>Once the height of <em>MainText</em>'s control area has been set, it cannot be changed without recreating the window.</p></dd>

  <dt>WinTitle</dt>
  <dd><p>The title of the window. If omitted and the window is being newly created, the title defaults to the name of the script (without path). If the <strong>B</strong> (borderless) option has been specified, there will be no visible title bar but the window can still be referred to by this title in commands such as <a href="WinMove.htm">WinMove</a>.</p></dd>

  <dt>FontName</dt>
  <dd><p>The name of the font to use for both <em>MainText</em> and <em>SubText</em>.  The <a href="../misc/FontsStandard.htm">font table</a> lists the fonts included with the various versions of Windows. If unspecified or if the font cannot be found, the system's default GUI font will be used.</p>
      <p>See the options section below for how to change the size, weight, and color of the font.</p></dd>

</dl>

<h2>Window Size, Position, and Behavior</h2>
<p><strong>A</strong>: The window will <u>not</u> be always-on-top.</p>
<p><strong>B</strong>: Borderless: The window will have no border and no title bar. To have a border but no title bar, use <strong>B1</strong> for a thin border or <strong>B2</strong> for a dialog style border.</p>
<p><strong>M</strong>: The window will be movable by the user (except if borderless). To additionally make the window resizable (by means of dragging its borders), specify <strong>M1</strong>. To additionally include a system menu and a set of minimize/maximize/close buttons in the title bar, specify <strong>M2</strong>.</p>
<p><strong>Pn</strong>: For Progress windows, specify for <strong>n</strong> the starting position of the bar (the default is 0 or the number in the allowable range that is closest to 0). To later change the position of the bar, follow this example: <code>Progress, 50</code>.</p>
<p><strong>Rx-y</strong>: For Progress windows, specify for <strong>x-y</strong> the numerical range of the bar (if the <strong>R</strong> option is not present, the default is 0-100). For example, <code>R0-1000</code> would allow a numbers between 0 and 1000; <code>R-50-50</code> would allow numbers between -50 and 50; and <code>R-10--5</code> would allow numbers between -10 and -5.</p>
<p><strong>T</strong>: The window will be given a button in the task bar and it will be unowned. Normally, there is no button because the window is owned by the script's main window. This setting also prevents a GUI window's <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a> setting from taking ownership of a Splash or Progress window.</p>
<p><strong>Hn</strong>: Specify for <strong>n</strong> the height of the window's client area (which is the area not including title bar and borders). If unspecified, the height will be calculated <u>automatically</u> based on the height of the image/bar and text in the window.</p>
<p><strong>Wn</strong>: Specify for <strong>n</strong> the width of the window's client area. If unspecified, the width will be calculated <u>automatically</u> for SplashImage (if there is an image). Otherwise, it will default to 300.</p>
<p><strong>Xn</strong>: Specify for <strong>n</strong> the x-coordinate of the window's upper left corner. If unspecified, the window will be horizontally centered on the screen.</p>
<p><strong>Yn</strong>: Specify for <strong>n</strong> the y-coordinate of the window's upper left corner. If unspecified, the window will be vertically centered on the screen.</p>
<p><strong>Hide</strong>: The window will be initially hidden. Use <code>Progress Show</code> or <code>SplashImage Show</code> to show it later.</p>
<h2>Layout of Objects in the Window</h2>
<p><strong>Cxy</strong>: Centered: If this option is absent, both <em>SubText</em> and <em>MainText</em> will be centered inside the window. Specify 0 for <strong>x</strong> to make <em>SubText</em> left-justified. Specify a 1 to keep it centered. The same is true for <strong>y</strong> except that it applies to <em>MainText</em> (<strong>y</strong> can be omitted). For example: <code>c10</code>.</p>
<p><strong>ZHn</strong>: Height of object: For Progress windows, specify for <strong>n</strong> the thickness of the progress bar (default 20). For SplashImage windows, specify for <strong>n</strong> the height to which to scale image. Specify -1 to make the height proportional to the  width specified in ZWn (i.e. &quot;keep aspect ratio&quot;). If unspecified, the actual image height will be used. In either case, a value of 0 can be specified to omit the object entirely, which allows the window to be used to display only text in custom fonts, sizes, and colors.</p>
<p><strong>ZWn</strong>: Width of object (for SplashImage windows only): Specify for <strong>n</strong> the width to which to scale the image.  Specify -1 to make the width proportional to the height specified in ZHn (i.e. &quot;keep aspect ratio&quot;). If unspecified, the actual image width will be used.</p>
<p><strong>ZXn</strong>: Specify for <strong>n</strong> the amount of margin space to leave on the left/right sides of the window. The default is 10 except for SplashImage windows with no text, which have a default of 0.</p>
<p><strong>ZYn</strong>: Specify for <strong>n</strong> the amount of vertical blank space to leave at the top and bottom of the window and between each control. The default is 5 except for SplashImage windows with no text, which have a default of 0.</p>
<p>Note: To create a vertical progress bar or to have more layout flexibility, use the <a href="Gui.htm">Gui</a> command such as this example:</p>
<pre>Gui, Add, Progress, Vertical vMyProgress
Gui, Show
return
<em>; ... later...</em>
GuiControl,, MyProgress, +10  <em>; Move the bar upward by 10 percent. Omit the + to set an absolute position.</em></pre>
<h2>Font Size and Weight</h2>
<p><strong>FMn</strong>: Specify for <strong>n</strong> the font size for <em>MainText</em>. Default 0, which causes 10 to be used on most systems. This default is not affected by the system's selected font size in Control Panel &gt; Display settings.</p>
<p><strong>FSn</strong>: Specify for <strong>n</strong> the font size for <em>SubText</em>. Default 0, which causes 8 to be used on most systems.</p>
<p><strong>WMn</strong>: Specify for <strong>n</strong> the font weight of <em>MainText</em>. The weight should be between 1 and 1000. If unspecified, 600 (semi-bold) will be used.</p>
<p><strong>WSn</strong>: Specify for <strong>n</strong> the font weight of <em>SubText</em>. The weight should be between 1 and 1000 (700 is traditionally considered to be &quot;bold&quot;). If unspecified, 400 (normal) will be used.</p>
<h2>Object Colors</h2>
<p>A color can be one of the names from the list below <u>or</u> a 6-digit hexadecimal RGB value. For example, specifying <code>cw1A00FF</code> would set a window background color with red component 1A, green component 00, and blue component FF.</p>
<p>Add a space after each color option if there are any more options that follow it. For example: <code>cbRed ct900000 cwBlue</code>.</p>
<p><strong>CBn</strong>: Color of progress bar: Specify for <strong>n</strong> one of the 16 primary HTML color names or a 6-digit RGB color value. If unspecified, the system's default bar color will be used. Specify the word Default to return to the system's default progress bar color.</p>
<p><strong>CTn</strong>: Color of text: Specify for <strong>n</strong> one of the 16 primary HTML color names or a 6-digit RGB color value. If unspecified, the system's default text color (usually black) will be used. Specify the word Default to return to the system's default text color.</p>
<p><strong>CWn</strong>: Color of window (background): Specify for <strong>n</strong> one of the 16 primary HTML color names or a 6-digit RGB color value. If unspecified, the system's color for the face of buttons will be used (specify the word Default to later return to this color). To make the background transparent, use <a href="WinSet.htm#TransColor">WinSet TransColor</a>.</p>
<table align="center" width="80%" border="0" cellspacing="10" cellpadding="0">
  <caption>
  <b><a name="colors"></a>Color names and RGB values</b>
  </caption>
  <tr>
    <td class="square" bgcolor="#000000">&nbsp;</td>
    <td>Black = 000000</td>
    <td class="square" bgcolor="#008000">&nbsp;</td>
    <td>Green = 008000</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#C0C0C0">&nbsp;</td>
    <td>Silver = C0C0C0</td>
    <td class="square" bgcolor="#00FF00">&nbsp;</td>
    <td>Lime = 00FF00</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#808080">&nbsp;</td>
    <td>Gray = 808080</td>
    <td class="square" bgcolor="#808000">&nbsp;</td>
    <td>Olive = 808000</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#FFFFFF">&nbsp;</td>
    <td>White = FFFFFF</td>
    <td class="square" bgcolor="#FFFF00">&nbsp;</td>
    <td>Yellow = FFFF00</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#800000">&nbsp;</td>
    <td>Maroon = 800000</td>
    <td class="square" bgcolor="#000080">&nbsp;</td>
    <td>Navy = 000080</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#FF0000">&nbsp;</td>
    <td>Red = FF0000</td>
    <td class="square" bgcolor="#0000FF">&nbsp;</td>
    <td>Blue = 0000FF</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#800080">&nbsp;</td>
    <td>Purple = 800080</td>
    <td class="square" bgcolor="#008080">&nbsp;</td>
    <td>Teal = 008080</td>
  </tr>
  <tr>
    <td class="square" bgcolor="#FF00FF">&nbsp;</td>
    <td>Fuchsia = FF00FF</td>
    <td class="square" bgcolor="#00FFFF">&nbsp;</td>
    <td>Aqua = 00FFFF</td>
  </tr>
</table>
<h2>Remarks</h2>
<p>If the first parameter is the word <strong>OFF</strong>, the window is destroyed.</p>
<p>Each script can display up to 10 Progress windows and 10 SplashImage windows. Each window has a number assigned to it at the time it is created. If unspecified, that number is 1 (the first). Otherwise, precede the first parameter with the number of the window followed by a colon. For example, the Progress command with <code>2:Off</code> would turn off the number-2 Progress window, <code>2:75</code> would set its bar to 75%, <code>2:</code> would change one or more of its text fields, and <code>2:B</code> would create a new borderless Progress window. Similarly, the SplashImage command with <code>2:Off</code> would turn off the number-2 SplashImage window, <code>2:</code> would change one or more of its text fields, and <code>2:C:\My Images\Picture1.jpg</code> would create a new number-2 SplashImage window.</p>
<p>Upon creation, a window that would be larger than the desktop is automatically shrunk to fit.</p>
<p>A naked progress bar can be displayed by specifying no <em>SubText</em>, no <em>MainText</em>, and including the following options: <code>b zx0 zy0</code>. A naked image can be displayed the same way except that only the B option is needed.</p>

<p>On Windows XP or later, if there is a non-Classic theme is in effect, the interior of a progress bar may appear as a series of segments rather than a smooth continuous bar. To avoid this, specify a bar color explicitly such as cbBlue.</p>
<p>Use decimal (not hexadecimal) numbers for option letters that need them, except where noted.</p>
<p>Commands such as <a href="WinSet.htm">WinSet</a> and <a href="WinMove.htm">WinMove</a> can be used to change the attributes of an existing window without having to recreate it.</p>
<p>A GUI window may take ownership of a Progress or Splash window by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>. This causes the Splash or Progress to stay always on top of its owner. In addition, the Progress or Splash is automatically destroyed when its GUI window is destroyed.</p>
<h2>Related</h2>
<p><a href="Gui.htm">GUI</a>, <a href="SplashTextOn.htm">SplashTextOn</a>, <a href="ToolTip.htm">ToolTip</a></p>
<h2>Examples</h2>
<pre class="NoIndent">Progress, b w200, My SubText, My MainText, My Title
Progress, 50 <em>; Set the position of the bar to 50%.</em>
Sleep, 4000
Progress, Off

<em>; Create a window just to display some 18-point Courier text:</em>
Progress, m2 b fs18 zh0, This is the Text.`nThis is a 2nd line., , , Courier New

<em>; Create a simple SplashImage window:</em>
SplashImage, C:\My Pictures\Company Logo.gif

<em>; Create a borderless SplashImage window with some large text beneath the image:</em>
SplashImage, C:\My Pictures\Company Logo.gif, b fs18, This is our company logo.
Sleep, 4000
SplashImage, Off

<em>; Here is a working example that demonstrates how a Progress window can be
; overlayed on a SplashImage to make a professional looking Installer screen:</em>
IfExist, C:\WINDOWS\system32\ntimage.gif, SplashImage, %A_WinDir%\system32\ntimage.gif, A,,, Installation
Loop, %A_WinDir%\system32\*.*
{
    Progress, %a_index%, %a_loopfilename%, Installing..., Draft Installation
    Sleep, 50
    if a_index = 100
        break
}
<em>; There is similar example at the bottom of the <a href="Gui.htm#Examples">GUI page</a>. Its advantage is that it uses only a single
; window and it gives you more control over window layout.</em></pre>

</body>
</html>
